home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat5 / ftn / datapool.z / datapool
Encoding:
Text File  |  2002-10-03  |  9.0 KB  |  211 lines
  1. DATAPOOL(5)                                           Last changed: 1-28-99
  2.  
  3.  
  4. NNAAMMEE
  5.      DDAATTAAPPOOOOLL - Fortran Interprocess Data Sharing
  6.  
  7. IIMMPPLLEEMMEENNTTAATTIIOONN
  8.      IRIX systems
  9.  
  10. DDEESSCCRRIIPPTTIIOONN
  11.      This man page describes Fortran datapool usage.  The information on
  12.      this man page is intended for use with the MIPSpro Fortran 77
  13.      compiler.  The man page can be used as both a quick reference and a
  14.      source of detailed information on datapool usage.
  15.  
  16.    DDaattaappooooll ddeeffiinniittiioonn aanndd ssyynnttaaxx
  17.      The DDAATTAAPPOOOOLL statement is a way for different processes to access the
  18.      same pool of common symbols, or _d_a_t_a_p_o_o_l.  Any processes can access
  19.      the shared datapool by linking with the datapool DSO (Dynamic Shared
  20.      Object).
  21.  
  22.      A DDAATTAAPPOOOOLL statement has the following syntax:
  23.  
  24.           DATAPOOL [/[_d_p//]] _n_l_i_s_t [[[[,,]]//[[_d_p]]// _n_l_i_s_t]] ......
  25.  
  26.      where _d_p is the datapool name and _n_l_i_s_t is a list of variable names,
  27.      array names, array declarators, or records.  A blank datapool, which
  28.      is unique by itself, is defined by omitting the _d_p argument.
  29.  
  30.      A datapool has similar syntactic form to a common block declaration.
  31.      However, in a common block, the common block variables are associated
  32.      with the same common block declared in other program units by their
  33.      relative position in the common block, regardless of the declared
  34.      symbolic names.  In a datapool, the datapool variables are associated
  35.      with declarations in other program units by their symbolic names,
  36.      regardless of the relative order, sizes, and number of variables
  37.      declared in the datapool for that particular program unit.  Also, no
  38.      datapool variables can be initialized with a DDAATTAA statement.
  39.  
  40.    DDaattaappooooll UUssaaggee
  41.      Follow these steps to use datapools:
  42.  
  43.      1. Put each blockdata containing one or more datapool definitions in a
  44.         Fortran source file.
  45.  
  46.      2. Compile the Fortran source file to create the object file (..oo file)
  47.         using the --GG00 option.
  48.  
  49.      3. Run the lldd command:
  50.  
  51.       ld -soname _d_p_f..ssoo --sshhaarreedd --nnooiivvppaadd --GG00 --oo _d_p_f..ssoo --iinniitt __iinniitt__ddpp___d_p_f__
  52.       --ffiinnii __uunnmmaapp__ddpp____  _d_p_f..oo
  53.  
  54.         where _d_p_f is the name of the Fortran source file without the ..ff
  55.         extension.  This creates the datapool DSO file ddppff..ssoo.
  56.  
  57.      4. Compile the rest of the Fortran program with the --GG00 option.
  58.  
  59.      5. Link all the Fortran objects with the selected datapool DSO's.  The
  60.         ..o files created from the datapool source files do need to be
  61.         linked to create the executable.
  62.  
  63.      6. When the program is run, the default directory for the shared
  64.         mapped data is //uussrr//ttmmpp.  The user can change this by setting the
  65.         DDAATTAAPPOOOOLL__DDIIRR environment variable to point to the desired
  66.         directory.
  67.  
  68.    DDaattaappooooll DDeettaaiillss
  69.      Each datapool item, when compiled, is turned into a separate external
  70.      symbol so it can be correctly associated with the same symbol declared
  71.      in other program units without being affected by its relative order in
  72.      the datapool.
  73.  
  74.      In one blockdata subprogram, and in only one, a datapool must be
  75.      defined as to its exact number of items, sizes, and relative order.
  76.      This will be used as the basis for sharing the datapool with other
  77.      processes wishing to access the same data.
  78.  
  79.      Each blockdata can contain definitions for one or more datapools.
  80.      However, each Fortran source file can contain only one such blockdata.
  81.      Each of those source files is turned into a DSO which any program can
  82.      link to if  the datapools defined in that blockdata need to be
  83.      accessed.  In other words, all datapools defined in a single blockdata
  84.      always go together as a single shared unit. If you want to choose the
  85.      datapools separately,  they have to be defined in different blockdata,
  86.      and put into separate Fortran source files.
  87.  
  88.      All datapool variables defined in the blockdata are mapped to a data
  89.      file which is shared between different processes.  The name of the
  90.      mapped data file is the name of the corresponding Fortran source files
  91.      preceded by DDPP__.  This file is put into the //uussrr//ttmmpp// directory as the
  92.      default, but this default directory can be changed with the
  93.      DDAATTAAPPOOOOLL__DDIIRR environment variable.  For example, datapools //aa//, //bb//,
  94.      and //cc// are defined in blockdata ddpp__aabbcc__ddeeff which is in the Fortran
  95.      source file ddppaabbcc..ff.   After compilation, the file ddppaabbcc..ff is
  96.      converted into ddppaabbcc..ssoo which an application can link with to share
  97.      the datapools //aa//, //bb//, and //cc//.  At runtime, a mapped data file,
  98.      //uussrr//ttmmpp//DDPP__ddppaabbcc, is created as the default.
  99.  
  100.      After all processes sharing this mapped datapool have terminated, the
  101.      mapped file is removed automatically.  However, if for any reason a
  102.      process using the datapool aborts abnormally before it can run to
  103.      completion, then the mapped file remains and  the user must remove the
  104.      file; otherwise, the next fresh process using the datapool will pick
  105.      up the values that have been mapped into that file.
  106.  
  107. NNOOTTEESS
  108.      * The following lines can be added to the MMAAKKEEFFIILLEE to create a
  109.        datapool DSO from the Fortran source file:
  110.  
  111.           .SUFFIXES : .so
  112.           FFLAGS = -G 0
  113.           LDFLAGS = -G 0
  114.           .f.so:
  115.                $(FC) $(FFLAGS) -c $*.f
  116.                $(LD) $(LDFLAGS) -soname $@ -shared -noivpad -o $@ \
  117.                    -init _init_dp_$*_ -fini _unmap_dp__ $*.o
  118.  
  119.      * For applications which rely on datapool variables being set to
  120.        zeroes at the beginning of execution, it is prudent to check for the
  121.        existence of the mapped data files //uussrr//ttmmpp//DDPP__**, which might remain
  122.        after an abnormal termination in previous runs.
  123.  
  124.      * Programs running on different machines can share datapools across
  125.        NFS by setting DDAATTAAPPOOOOLL__DDIIRR to point to the same physical directory.
  126.        However, because I/O operations are buffered across NFS, changing a
  127.        datapool variable on one system does not cause the new value to be
  128.        written immediately in the data file and so it is not known by a
  129.        different process on another system.  It will be up to the user to
  130.        create his own datapool status variable to ensure the update of the
  131.        datapool variables by another process on a different system.
  132.  
  133.      * At runtime, the datapool DSOs must be in the search path of rrlldd for
  134.        them to be found.  The default search path can be changed by setting
  135.        the environment variable LLDD__LLIIBBRRAARRYY__PPAATTHH.
  136.  
  137.      * The datapool DSOs cannot be used with IRIX releases before 5.1.1.
  138.        You receive an error message that the DSO's are not found when a
  139.        datapool application is run on those releases even when the DSOs
  140.        exist.
  141.  
  142. EEXXAAMMPPLLEESS
  143.   ::::::::::::::
  144.   testdp.f
  145.   ::::::::::::::
  146.   C
  147.   C NAME
  148.   C       testdp.f - Shared DATAPOOL test case
  149.   C
  150.   C    Note that both the sizes and the relative order of the datapool
  151.   C    items are different from the defined sizes and order in the
  152.   C    blockdata
  153.  
  154.           datapool /hello/ c, b, arr(100,100,3)
  155.           real*8 arr
  156.  
  157.           print *, 'Read arr(1,1,1)', arr(1,1,1)
  158.           if (arr(1,1,1) .ne. 42) then
  159.               arr(1,1,1) = 42
  160.           endif
  161.  
  162.           print *, "Address Offset = ", %loc(b)-%loc(arr), %loc(c) -%loc(b)
  163.           call sleep(10)
  164.           end
  165.  
  166.   ::::::::::::::
  167.   hello.f
  168.   ::::::::::::::
  169.           blockdata hellodef
  170.   C    The relative positions and sizes of the datapool items are
  171.   C    defined in this blockdata and nowhere else.
  172.           real*8 arr
  173.           datapool /hello/ arr(100,100,30), b, c
  174.           end
  175.  
  176.   ::::::::::::::
  177.   Makefile
  178.   ::::::::::::::
  179.   .SUFFIXES : .so
  180.   CFLAGS = -G 0
  181.   FFLAGS = -G 0
  182.   FFILES = testdp.f hello.f
  183.  
  184.   default: testdp
  185.  
  186.   testdp: testdp.o hello.so
  187.           $(FC) $(FFLAGS) -o testdp         testdp.o hello.so
  188.  
  189.   .f.so:
  190.           $(FC) $(FFLAGS) -c $*.f
  191.           $(LD) -soname $@ -shared -noivpad $*.o -G 0 -o $@ \
  192.             -init _init_dp_$*_ -fini _unmap_dp__
  193.  
  194.   test: default
  195.           testdp &
  196.           @ sleep 1
  197.           testdp &
  198.  
  199.   clean:
  200.           rm -f *.o core a.out *.so
  201.  
  202.   clobber: clean
  203.           rm -f testdp so_locations
  204.  
  205. SSEEEE AALLSSOO
  206.      ff7777(1), ddssoo(5), lldd(1), rrlldd(1)
  207.  
  208.      _M_I_P_S_p_r_o _F_o_r_t_r_a_n _7_7 _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e
  209.  
  210.      This man page is available only online.
  211.